Minor edits to super command doc #5487
Conversation
| and both are equivalent to the classic SQL | ||
| ``` | ||
| super -c "SELECT typeof(this) FROM example.json" |
There was a problem hiding this comment.
I'm still getting the feel for when and how much to reassure readers that standard SQL is still in there. I know we've talked about covering this topic in more detail when we get to overhauling the Language docs. Regardless, my instincts are to make some nods to classic SQL early in individual docs pages since we can't always be sure where users will first land and we can't be confident they'll always click on links when we hope they will. While we hope that users will quickly catch on to SuperSQL's pipe extensions so they can do things with super-structured data that classic SQL can't, I also want to make it as clear as possible to the new users that learning new elements are not a prerequisite to getting started, hence my addition of this new text.
Also related to this is when to use ALL CAPS. Once again, it feels worthwhile to use all caps in contexts where we're showing pure SQL that could drop directly into some other classic relational system. Likewise if we're showing an example that learns mostly/exclusively on SuperSQL shortcuts it seems reasonable to opt for lowercase, even if the example shares a few keywords common in classic SQL. Then there seems to be a gray area when it's a mix. On the whole though, my instincts are to start from all caps when possible to maximize approachability to the SQL-centric audience.
| @@ -139,14 +143,14 @@ The input format is typically [detected automatically](#auto-detection) and the | |||
| "Auto" is "yes" in the table above support _auto-detection_. | |||
| Formats without auto-detection require the `-i` option. | |||
|
|
|||
| ### Hard-wired Input Format | |||
| #### Hard-wired Input Format | |||
There was a problem hiding this comment.
In #5481, a new "Data Formats" section was created and the "Input Formats" and "Output Formats" sub-sections were moved below that, which all makes sense. However, the sub-sections under "Input Formats" and "Output Formats" were left at their prior level, so the hierarchical order was disrupted. This and other ####-style changes in this PR are to correct that.
These are some minor changes that come to mind while I was reviewing #5481.
This only touches the first half of the doc and not the second half with the Performance section. I've been writing some scripts to make it easy to run those queries and assemble the results so we can revisit them frequently and also point users at a way to run them easily on an AWS instance as neutral turf. I'll put up a separate PR next with those changes.